%% Kalman Filter with Nonlinear Prediction Step
% by Jaromir Benes
%
% Run the Kalman filter with a nonlinear prediction step
% to filter the data simulated previously in `stochastic_simulations`.
% With a linear prediction step, the credibility process doesn't respond to
% inflation performance and doesn't affect the rest of the economy. When
% the nonlinearity is preserved in the prediction step, the results get
% much more accurate.

%% Clear Workspace

clear;
close all;
home;
irisrequired 20140401;

%% Load Model Object
%
% This file uses the model object and simulated database from
% `stochastic_simualtions`. Run `stochastic_simulations` prior to this
% m-file.

load stochastic_simulations m s3;

%% Kalman Filter with Nonlinear Prediction Step
%
% Use the database `s3` with measurement variables (output, inflation,
% interest rates) simulated in `stochastic_simulations`. These will be the
% only input into the Kalman filter.
%
% Run the Kalman filter twice. In the first run, the Kalman filter uses
% the linearised model to produce one-step-ahead predictions in each of its steps.
% In the second run, the Kalman filter calls a simulation in an exact
% nonlinear mode to produce one-step-ahead predictions. Note that the
% exact nonlinear mode requires more periods to be simulated than are
% actually needed.
%
% Initialise the Kalman filter using the actual simulated data <?init?>.
% The initial condition is now being treated as a fixed, deterministic
% point.

g = struct();
g.Y = s3.Y;
g.PI = s3.PI;
g.R = s3.R;

[~,f1] = filter(m,g,4:20, ...
    'initcond=',s3, ... %?init?
    'meanonly=',true,'data=','pred,smooth');

[~,f2] = filter(m,g,4:20, ...
    'initcond=',s3, ... %?init?
    'meanonly=',true,'data=','pred,smooth', ...
    'nonlinear=',15);

% ...
%
% Use the option `'simulate='` to modify the nonlinear simulation options,
% such as max number of iterations or output printed on the screen. For
% instance, set `'display'` to `0` to completely switch off the screen
% reports produced on nonlinear simulations in each Kalman step:
%
%     [~,f2] = filter(m,g,4:20, ...
%         'initcond=',s3, ...
%         'meanonly=',true,'data=','pred,smooth', ...
%         'nonlinear=',15, ...
%         'simulate=',{'display=',0});
%

%% Plot Kalman Smoother
%
% Plot the smoother results from the Kalman filters with linearized versus
% nonlinear prediction step, and the true simulated data.

dbplot(f1.smooth & f2.smooth & s3,1:20, ...
    {'"Inflation" pi', ...
    '"Credibility" c', ...
    '"Output gap" y', ...
    '"Policy rate" r'}, ...
    'zeroline=',true,'tight=',true,'marker=','.','highlight=',1:3);

grfun.bottomlegend('Filter with Linearized Prediction Step', ...
    'Filter with Nonlinear Prediction Step', ...
    'True Simulated Values');

grfun.ftitle('Kalman Smoother');

%% Plot Kalman Predictions
%
% Plot the prediction steps performed in the Kalman filters with linearized
% versus nonlinear prediction step, and the true simulated data.

dbplot(f1.pred & f2.pred & s3,1:20, ...
    {'"Inflation" pi', ...
    '"Credibility" c', ...
    '"Output gap" y', ...
    '"Policy rate" r'}, ...
    'zeroline=',true,'tight=',true,'marker=','.','highlight=',1:3);

grfun.bottomlegend('Filter with Linearized Prediction Step', ...
    'Filter with Nonlinear Prediction Step', ...
    'True Simulated Values');

grfun.ftitle('Kalman Predictions');

%% Help on IRIS Functions Used in This File
%
% Use either `help` to display help in the command window, or `idoc`
% to display help in an HTML browser window.
%
%    help model/filter
%    help dbase/dbplot
%    help grfun/bottomlegend
%    help grfun/ftitle
